//
// Created on 2025/9/5.
//
// Node APIs are not fully supported. To solve the compilation error of the interface cannot be found,
// please include "napi/native_api.h".

#ifndef MINDSPORE_LITE_LLMINFERNATIVE_H
#define MINDSPORE_LITE_LLMINFERNATIVE_H

#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 定义指向底层C++ LLMInfer对象的匿名句柄，用于C语言接口隐藏实现细节
 */
typedef void *LLMInferHandle_t;

/**
 * @brief 异步生成文本结果的回调函数类型定义
 * @param result 生成完成的文本结果（以空字符结尾的C字符串）
 * @param user_data 用户传入的自定义数据指针
 */
typedef void (*Generate_Callback_t)(const char *result, void *user_data);

/**
 * @brief 创建LLM推理器原生对象实例
 * @return LLMInferHandle_t 成功返回新创建的句柄，失败返回NULL
 * @note 使用者需负责调用LLMInfer_Native_Destroy销毁返回的句柄[3](@ref)
 */
LLMInferHandle_t LLMInfer_Native_Create();

/**
 * @brief 销毁LLM推理器实例并释放所有相关资源
 * @param handle 由LLMInfer_Native_Create创建的句柄
 * @warning 传入无效句柄可能导致未定义行为[3](@ref)
 */
void LLMInfer_Native_Destroy(LLMInferHandle_t handle);

/**
 * @brief 初始化并构建LLM推理器
 * @param handle LLM推理器句柄
 * @param generate_params 生成参数配置（JSON格式字符串）
 * @param model_file_path 模型文件路径
 * @param is_record_perf_data 是否记录性能数据
 * @return int 成功返回0，失败返回错误码
 * @note 必须在调用生成函数前成功执行此函数[6](@ref)
 */
int LLMInfer_Native_Build(LLMInferHandle_t handle, const char *model_file_path, const char *generate_params,
                          bool is_record_perf_data);

/**
 * @brief 检查最近的异步生成操作是否已完成
 * @param handle LLM推理器句柄
 * @return bool true-生成已完成/未进行; false-生成正在进行中
 */
bool LLMInfer_Native_Generate_Is_End(LLMInferHandle_t handle);

/**
 * @brief 请求停止当前正在进行的生成操作
 * @param handle LLM推理器句柄
 * @return int 成功返回0，失败返回错误码
 * @note 此函数为异步请求，生成操作不会立即停止[6](@ref)
 */
int LLMInfer_Native_Stop_Generate(LLMInferHandle_t handle);

/**
 * @brief 执行文本生成并支持性能回调（阻塞模式）
 * @param handle LLM推理器句柄
 * @param input_text 输入文本（以空字符结尾的C字符串）
 * @param output_text 输出参数，指向生成结果的指针（需调用者释放）
 * @param callback 生成过程中定期调用的回调函数（可为NULL）
 * @param user_data 传递给回调函数的用户数据
 * @return int 成功返回0，失败返回错误码
 * @warning 输出文本缓冲区需由调用者使用free()释放[3,6](@ref)
 */
int LLMInfer_Native_Generate_With_Perf_CallBack(LLMInferHandle_t handle, const char *input_text, char **output_text,
                                                Generate_Callback_t callback, void *user_data);

/**
 * @brief 执行同步文本生成（阻塞模式）
 * @param handle LLM推理器句柄
 * @param input_text 输入文本（以空字符结尾的C字符串）
 * @param output_text 输出参数，指向生成结果的指针（需调用者释放）
 * @return int 成功返回0，失败返回错误码
 * @warning 输出文本缓冲区需由调用者使用free()释放[3,6](@ref)
 */
int LLMInfer_Native_Generate(LLMInferHandle_t handle, const char *input_text, char **output_text);

/**
 * @brief 执行异步文本生成（流式）
 * @param handle LLM推理器句柄
 * @param input_text 输入文本（以空字符结尾的C字符串）
 * @return int 成功返回0，失败返回错误码
 */
int LLMInfer_Native_Generate_Stream(LLMInferHandle_t handle, const char *input_text);

/**
 * @brief 启动异步文本生成（非阻塞模式）
 * @param handle LLM推理器句柄
 * @param input_text 输入文本（以空字符结尾的C字符串）
 * @return int 成功返回0，失败返回错误码
 */
int LLMInfer_Native_Generate_Async(LLMInferHandle_t handle, const char *input_text);

/**
 * @brief 获取异步生成操作的结果
 * @param handle LLM推理器句柄
 * @param output_text 输出参数，指向生成结果的指针（内存由库管理，在下次调用前有效）
 * @return int 成功返回0，失败返回错误码
 * @note 仅在LLMInfer_Native_Generate_Is_End返回true时调用此函数[6](@ref)
 */
int LLMInfer_Native_Get_Generate_Async_Result(LLMInferHandle_t handle, char **output_text);

/**
 * @brief 获取流式输出tokens（流式）
 * @param handle LLM推理器句柄
 * @param output_text 输出参数，指向生成结果的指针（需调用者释放）
 * @param is_end 输出参数，是否已经结束推理
 * @return int 成功返回0，失败返回错误码
 * @warning 输出文本缓冲区需由调用者使用free()释放[3,6](@ref)
 */
int LLMInfer_Native_Stream_Word(LLMInferHandle_t handle, char **output_text, bool *is_end);

#ifdef __cplusplus
}
#endif
#endif // MINDSPORE_LITE_LLMINFERNATIVE_H
